This command supports monitoring the usage of system resources.
Resources are represented by various metrics associated with the host
system or a particular VM. For example, the host system has a
CPU/Load/User metric that shows the
percentage of time CPUs spend executing in user mode over a specific
sampling period.
Metric data is collected and retained internally; it may be
retrieved at any time with the VBoxManage metrics
query subcommand. The data is available as long as the
background VBoxSVC process is alive. That
process terminates shortly after all VMs and frontends have been closed.
By default metrics are not collected. Metrics collection starts as
soon as a proper sampling interval and the number of retained metrics are
set using the VBoxManage metrics setup
subcommand. The interval is measured in seconds. For example, to enable
collecting the host processor and memory usage metrics every second and
keeping the 5 most current samples, the following command can be used:
VBoxManage metrics setup -period 1 -samples 5 host CPU/Load,RAM/Usage
Specifying 0 as the interval or as
the number of retained samples disables metric collection. Note that the
VBoxManage metrics setup subcommand
discards all previously collected samples for the specified set of objects
and metrics.
The host and VMs have different sets of associated metrics.
Available metrics can be listed with VBoxManage metrics
list subcommand.
A complete metric name may include an aggregate function. The name
has the following form:
Category/Metric[/SubMetric][:aggregate].
For example, RAM/Usage/Free:min stands
for the minimum amount of available memory over all retained data if
applied to the host object.
Subcommands may apply to all objects and metrics or can be limited
to one object or/and a list of metrics. If no objects or metrics are given
in the parameters, the subcommands will apply to all available metrics of all
objects. You may use an asterisk (" *")
to explicitly specify that the command should be applied to all objects or
metrics. Use "host" as the object name to limit the scope of the command
to host-related metrics. To limit the scope to a subset of metrics, use
a metric list with names separated by commas.
For example, to query metric data on the CPU time spent in user and kernel modes by the virtual machine named "test", you can use the following command:
VBoxManage query test CPU/Load/User,CPU/Load/Kernel
The following list summarizes the available subcommands:
This subcommand shows the parameters of the currently existing metrics. Note that VM-specific metrics are only available when a particular VM is running.
This subcommand sets the interval between taking two samples
of metric data and the number of samples retained internally. The
retained data is available for displaying with the query
subcommand.
This subcommand retrieves and displays the currently retained metric data.
query subcommand does not remove or "flush"
retained data. If you query often enough you will see how old
samples are gradually being "phased out" by new samples.This subcommand sets the interval between taking two samples
of metric data and the number of samples retained internally. The
collected data is displayed periodically until Ctrl-C is pressed unless
the -detach option is specified. With the -detach
option, this subcommand operates the same way as setup
does. The -list option shows which metrics match the
specified filter.